Add Structlog Handler as Instrumentation by JWinermaSplunk · Pull Request #4286 · open-telemetry/opentelemetry-python-contrib

JWinermaSplunk · 2026-03-03T21:22:02Z

Description

Please include a summary of the change and which issue is fixed. Please also include relevant motivation and context. List any dependencies that are required for this change.

Fixes open-telemetry/opentelemetry-python#2993

Type of change

Please delete options that are not relevant.

Bug fix (non-breaking change which fixes an issue)
New feature (non-breaking change which adds functionality)
Breaking change (fix or feature that would cause existing functionality to not work as expected)
This change requires a documentation update

How Has This Been Tested?

Please describe the tests that you ran to verify your changes. Provide instructions so we can reproduce. Please also list any relevant details for your test configuration

test_structlog.py

Does This PR Require a Core Repo Change?

Yes. - Link to PR:
No.

Checklist:

See contributing.md for styleguide, changelog guidelines, and more.

Followed the style guidelines of this project
Changelogs have been updated
Unit tests have been added
Documentation has been updated

tammy-baylis-swi · 2026-03-19T20:33:31Z

+    return _STD_TO_OTEL[levelno]
+
+
+class StructlogHandler:


Could this be simplified by subclassing an existing type in structlog (which I don't know that well 🙂 )?

tammy-baylis-swi · 2026-03-19T20:35:56Z

Thank you for undertaking this!

tammy-baylis-swi · 2026-03-25T21:45:09Z

I think a rebase is needed. This PR is now reverting some unrelated docker-test fixes (this other PR)

JWinermaSplunk · 2026-03-25T21:49:51Z

I think a rebase is needed. This PR is now reverting some unrelated docker-test fixes (this other PR)

Believe I went ahead and rebased, but feel free to let me know if it still looks off!

dodofarm · 2026-04-18T00:27:07Z

Hey team,
any timeline on this PR? This is a great addition that we've been anticipating for quite some time!

# Conflicts: # .github/workflows/test_0.yml # .github/workflows/test_1.yml # .github/workflows/test_2.yml # opentelemetry-contrib-instrumentations/pyproject.toml # Conflicts: # .github/workflows/core_contrib_test.yml

# Conflicts: # .github/workflows/test_1.yml # .github/workflows/test_2.yml # .github/workflows/test_3.yml

pmcollins

Hey Josh, this instrumentation seems to work fine, but I added some comments.

pmcollins · 2026-04-22T16:49:23Z

+    return None
+
+
+class StructlogHandler:


Would it be preferable to call this a StructlogProcessor since that's what structlog calls them? Also, below, we have processor = StructlogHandler(logger_provider=logger_provider).

Fair point, I can adjust the line below, but I went with handler instead of processor to follow the logging handler from logging instrumentation, I believe. Thoughts?

The LoggingHandler name makes sense because it's a subclass of logging.Handler. In this case the class doesn't extend anything -- it's just a callable that structlog considers a processor. I don't see a need to match terminology with that library, but won't block on this if you disagree.

pmcollins · 2026-04-22T17:20:04Z

+            if dt.tzinfo is None:
+                dt = dt.replace(tzinfo=timezone.utc)


Not sure we want this because we could be classifying a local timestamp as UTC here. For example, one of the default structlog processors is TimeStamper(fmt="%Y-%m-%d %H:%M:%S", utc=False) which doesn't include a %z, so the emitted string doesn't include a timezone component, tzinfo is None, and we'd be then shifting the time to UTC.

pmcollins · 2026-04-22T17:29:40Z

+        StructlogInstrumentor._processor = processor
+
+        # Wrap structlog.configure so that if user code calls it after
+        # instrumentation, the handler is re-inserted into the new chain.
+        StructlogInstrumentor._original_configure = structlog.configure


Can we convert these class variables to instance variables?

I might be wrong, but isn't this the same behavior as existing instrumentations that use BaseInstrumentor and therefore would be protected by that singleton guard?

Yeah, but I think variables should have the narrowest scope possible.

pmcollins · 2026-04-22T17:31:47Z

+        # instrumentation, the handler is re-inserted into the new chain.
+        StructlogInstrumentor._original_configure = structlog.configure
+
+        def _patched_configure(**kwargs):


nit: since this is a closure I don't think you need the leading underscore.

pmcollins · 2026-04-22T17:45:07Z

+        if StructlogInstrumentor._processor is None:
+            return


I'm not sure this test is necessary -- looks like the only way _processor can be None is if the user calls uninstrument without calling instrument, but seems like that's guarded against by the parent class. Which means the class variable can go away and patched_configure can just refer to _processor as a local (or just processor) since it's a closure.

pmcollins · 2026-04-22T17:54:09Z

+                    )
+                    kwargs["processors"] = processors
+            original = StructlogInstrumentor._original_configure
+            if original is not None:


Can original be None here? Might be an unnecessary test.

pmcollins · 2026-04-22T18:02:45Z

+
+        # Get the log level and map to OTel severity
+        level_str = event_dict.get("level", "info")
+        levelno = _STRUCTLOG_LEVEL_TO_LEVELNO.get(level_str.lower(), 20)


Looks like 20 maps to INFO -- might be more appropriate to use Otel's UNSPECIFIED level that maps to 0. You may be able to use SeverityNumber.UNSPECIFIED in the API package.

pmcollins · 2026-04-22T18:09:24Z

+        # Handle exception information
+        exc_info = event_dict.get("exc_info")
+
+        if exc_info is True:


Might want to add a comment here that is True is required to prevent matching on a non-empty tuple or exception which are also truthy. (Pycharm linter is flagging this)

JWinermaSplunk marked this pull request as ready for review March 13, 2026 17:14

JWinermaSplunk requested a review from a team as a code owner March 13, 2026 17:14

JWinermaSplunk changed the title ~~[WIP] Add Structlog Handler as Instrumentation~~ Add Structlog Handler as Instrumentation Mar 13, 2026

github-project-automation Bot added this to Python PR digest Mar 13, 2026

JWinermaSplunk force-pushed the structlog-handler branch from e0317fa to fab1022 Compare March 13, 2026 17:20

tammy-baylis-swi reviewed Mar 19, 2026

View reviewed changes

Comment thread ...ntelemetry-instrumentation-structlog/src/opentelemetry/instrumentation/structlog/__init__.py Outdated

tammy-baylis-swi reviewed Mar 19, 2026

View reviewed changes

Comment thread ...ntelemetry-instrumentation-structlog/src/opentelemetry/instrumentation/structlog/__init__.py Outdated

pmcollins reviewed Mar 19, 2026

View reviewed changes

Comment thread opentelemetry-instrumentation/src/opentelemetry/instrumentation/bootstrap_gen.py Outdated

Comment thread ...ntelemetry-instrumentation-structlog/src/opentelemetry/instrumentation/structlog/__init__.py

JWinermaSplunk force-pushed the structlog-handler branch from fd07c37 to ddae8b5 Compare March 19, 2026 23:11

xrmx moved this to Reviewed PRs that need fixes in Python PR digest Mar 25, 2026

tammy-baylis-swi reviewed Mar 25, 2026

View reviewed changes

Comment thread ...ntelemetry-instrumentation-structlog/src/opentelemetry/instrumentation/structlog/__init__.py

JWinermaSplunk force-pushed the structlog-handler branch from ef6ad9a to ece1f64 Compare March 25, 2026 21:48

tammy-baylis-swi reviewed Mar 25, 2026

View reviewed changes

Comment thread CHANGELOG.md Outdated

tammy-baylis-swi approved these changes Mar 25, 2026

View reviewed changes

JWinermaSplunk added 10 commits April 20, 2026 09:38

initial commit

0e575ed

# Conflicts: # .github/workflows/test_0.yml # .github/workflows/test_1.yml # .github/workflows/test_2.yml # opentelemetry-contrib-instrumentations/pyproject.toml # Conflicts: # .github/workflows/core_contrib_test.yml

change to StructlogHandler, updates

48cf0de

update CHANGELOG, updates

acff5c6

fix checks

457df12

# Conflicts: # .github/workflows/test_1.yml # .github/workflows/test_2.yml # .github/workflows/test_3.yml

comments

a3ac5a0

add log_utils

4c23aef

tox

734effe

internal comments

988d42a

tox

647b874

rebase, tox

26c68f5

JWinermaSplunk force-pushed the structlog-handler branch from 2648150 to 26c68f5 Compare April 20, 2026 16:50

JWinermaSplunk added 2 commits April 20, 2026 10:16

update deps

ae5de4e

internal comments

4c55894

pmcollins reviewed Apr 22, 2026

View reviewed changes

Conversation

JWinermaSplunk commented Mar 3, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Description

Type of change

How Has This Been Tested?

Does This PR Require a Core Repo Change?

Checklist:

Uh oh!

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Uh oh!

tammy-baylis-swi commented Mar 19, 2026

Uh oh!

Uh oh!

Uh oh!

Uh oh!

tammy-baylis-swi commented Mar 25, 2026

Uh oh!

JWinermaSplunk commented Mar 25, 2026

Uh oh!

Uh oh!

dodofarm commented Apr 18, 2026

Uh oh!

pmcollins left a comment

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

5 participants

JWinermaSplunk commented Mar 3, 2026 •

edited

Loading